/*
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

/*
 *
 *
 *
 *
 *
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package java.util.concurrent;

import java.util.function.Consumer;
import java.util.function.BiConsumer;
import java.util.function.Function;
import java.util.function.BiFunction;


/**
 * 表示一个异步计算的完成阶段，提供了对计算结果的进一步处理的能力。
 * 它是一个用于表示异步计算结果的接口，允许在计算完成后执行额外的操作。
 * CompletionStage是反应式编程的一部分，用于处理异步编程中的结果处理、错误处理和回调函数。
 */
public interface CompletionStage<T> {


    // 第一类接口, 返回结果

    /**
     * 上一个阶段执行完毕,正常结果做参数执行下一个Function返回结果
     */
    public <U> CompletionStage<U> thenApply(Function<? super T, ? extends U> fn);

    public <U> CompletionStage<U> thenApplyAsync(Function<? super T, ? extends U> fn);

    public <U> CompletionStage<U> thenApplyAsync(Function<? super T, ? extends U> fn, Executor executor);


    /**
     * 上两个阶段同时执行完毕,正常结果做参数执行下一个BiFunction返回结果
     */
    public <U, V> CompletionStage<V> thenCombine(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn);

    public <U, V> CompletionStage<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn);

    public <U, V> CompletionStage<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn, Executor executor);


    /**
     * 上两个阶段任一执行完毕,正常结果做参数执行下一个Function返回结果
     */
    public <U> CompletionStage<U> applyToEither(CompletionStage<? extends T> other,
                                                Function<? super T, U> fn);

    public <U> CompletionStage<U> applyToEitherAsync
            (CompletionStage<? extends T> other,
             Function<? super T, U> fn);

    public <U> CompletionStage<U> applyToEitherAsync
            (CompletionStage<? extends T> other,
             Function<? super T, U> fn,
             Executor executor);


    // 第二类结构, 不返回结果

    /**
     * 上一阶段执行完毕,结果参数执行下一个function 不返回结果
     */
    public CompletionStage<Void> thenAccept(Consumer<? super T> action);

    public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action);

    public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action, Executor executor);


    /**
     * 上两个阶段同时执行完毕,结果做参数执行下一个function 不返回结果
     */
    public <U> CompletionStage<Void> thenAcceptBoth(CompletionStage<? extends U> other,
                                                    BiConsumer<? super T, ? super U> action);

    public <U> CompletionStage<Void> thenAcceptBothAsync(CompletionStage<? extends U> other,
                                                         BiConsumer<? super T, ? super U> action);

    public <U> CompletionStage<Void> thenAcceptBothAsync(CompletionStage<? extends U> other,
                                                         BiConsumer<? super T, ? super U> action,
                                                         Executor executor);


    /**
     * 上两个阶段任一执行完毕,结果做参数执行下一个function 不返回结果
     */
    public CompletionStage<Void> acceptEither(CompletionStage<? extends T> other,
                                              Consumer<? super T> action);

    public CompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other,
                                                   Consumer<? super T> action);

    public CompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other,
                                                   Consumer<? super T> action,
                                                   Executor executor);

    /**
     * 上一阶段执行完毕,执行下一阶段
     */
    public CompletionStage<Void> thenRun(Runnable action);

    public CompletionStage<Void> thenRunAsync(Runnable action);

    public CompletionStage<Void> thenRunAsync(Runnable action, Executor executor);


    /**
     * 上两个阶段同事执行完毕,执行下一阶段
     */
    public CompletionStage<Void> runAfterBoth(CompletionStage<?> other,
                                              Runnable action);

    public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
                                                   Runnable action);

    public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,
                                                   Runnable action,
                                                   Executor executor);


    /**
     * 上两个阶段任一执行完毕,执行下一阶段
     */
    public CompletionStage<Void> runAfterEither(CompletionStage<?> other,
                                                Runnable action);

    public CompletionStage<Void> runAfterEitherAsync
            (CompletionStage<?> other,
             Runnable action);

    public CompletionStage<Void> runAfterEitherAsync
            (CompletionStage<?> other,
             Runnable action,
             Executor executor);


    /**
     * 基于上一阶段正常执行完毕的状态,执行下一阶段
     */
    public <U> CompletionStage<U> thenCompose
            (Function<? super T, ? extends CompletionStage<U>> fn);

    public <U> CompletionStage<U> thenComposeAsync
            (Function<? super T, ? extends CompletionStage<U>> fn);

    public <U> CompletionStage<U> thenComposeAsync
            (Function<? super T, ? extends CompletionStage<U>> fn,
             Executor executor);


    /***
     * 基于上一阶段执行完毕的状态,执行下一阶段,即使执行异常也有反馈执行下一阶段
     */
    public <U> CompletionStage<U> handle
            (BiFunction<? super T, Throwable, ? extends U> fn);

    public <U> CompletionStage<U> handleAsync
            (BiFunction<? super T, Throwable, ? extends U> fn);

    public <U> CompletionStage<U> handleAsync
            (BiFunction<? super T, Throwable, ? extends U> fn,
             Executor executor);


    /**
     * 基于上一阶段执行完毕的状态和结果,执行下一阶段,即使执行异常也有反馈执行下一阶段
     */
    public CompletionStage<T> whenComplete
            (BiConsumer<? super T, ? super Throwable> action);

    public CompletionStage<T> whenCompleteAsync
            (BiConsumer<? super T, ? super Throwable> action);

    public CompletionStage<T> whenCompleteAsync
            (BiConsumer<? super T, ? super Throwable> action,
             Executor executor);


    /**
     * 上阶段执行异常处理
     */
    public CompletionStage<T> exceptionally
            (Function<Throwable, ? extends T> fn);


    /**
     * 接口实现类之间相互转换
     */
    public CompletableFuture<T> toCompletableFuture();

}
